PTV Drive&Arrive | API Guide > API Description > /subscription/_POST_SSE

Subscriptions

PTV Drive&Arrive supports the following concepts for subscriptions to provide notifications about diverse events for listening clients:

CALLBACK_URL: If a running public HTTP-server is available, this concept can be used. A HTTP callback is provided client-side and called by PTV Drive&Arrive, For best results, it is recommended using this concept for subscriptions.
PUSH_NON_MOBILE_SSE ( SSE = server-sent events): SSE can be used if a mobile / desktop application or a system behind a firewall is used and not any public HTTP-server is available. A permanent connection, i.e. web socket, is established during lifetime of the subscription.
PUSH_MOBILE : can be used for popular mobile OS like Android or iOS but also for web applications.
PUSH_NON_MOBILE (Signal-R) DEPRECATED

Subscriptions can be done via calling the following POST methods.

/subscription/ POST - create a SSE subscription for specified SCEM-ID

Before you can subscribe to PTV Drive&Arrive you have to establish a SSE connection. Please refer to http://docs.servicestack.net/server-events and see our code-sample for .net or JavaScript.

{ 
 "subscription": {
  "notificationType": "PUSH_NON_MOBILE_SSE",	   // type of notification channel, here SSE
  "topicType": "ETA",                              // (optional) ETA, TOUR_UPDATE
  "notificationDescription":{
   "ident" : "<identifier of SSE connection>"      // notificationHandler.GetNotificationHub(...).Ident in C#.net code sample
  },
  "scemid": "X9X9X9X9X9"			   // SCEM-ID of tour or stop that should be get notifications
 },
 "source": "MYPRODUCT_V2.8"                        // User defined value which describes the originator of the event. e.g. PTVEMAPP_<system>_<version>, ptvemportal, jmeter_<testnumber> ...
}

Result

{
	"subscriptionID": "1655eb2a547f4f8c900ea64300814d52",
	"scemid": "X9X9X9X9X9",
	"responseStatus": {
		"errorCode": "SUCCESS",
		"message": "00000000000000000000000000000000"
	}
}

Will be subscribed to a SSE channel with a specific identifier.

Exceptions

validation / message	errorCode
Please provide an ident for the connection.	INVALID_NOTIFICATION_CONTENT
SCEM-ID should be a 10-digit, case-sensitive, alphanumeric identifier of an existing tour or stop.	SCEMID_INVALID

/subscription/ POST - HTTP callback

A public (not behind a firewall) HTTP server is needed. For testing purposes you can use http://requestb.in. You can also use HTTPS as protocol but must have a valid HTTPS certificate, otherwise a connection will not be established. To get notifications based on HTTP Callback you must call https://driveandarrive-v1.cloud.ptvlogistics.com/em/subscription?source=<myProduct_Vx.y> with HTTP-POST and the following data:

{
 "subscription": {
   "notificationType": "CALLBACK_URL",		// type of notification channel, here HTTP callback
   "topicType": "ETA",                          // (optional) ETA, TOUR_UPDATE
   "notificationDescription": {			// notification details
     "callBackURL":"http://requestb.in/x9x9x9x9", // URL of your server
     "ident": "your_identifier"			// (optional) your personal identifier, e.g. system-XY - can be used for debugging purposes
   },
   "scemid": "X9X9X9X9X9"			// SCEM-ID of tour or stop you will receive notifications from
 },
 "source": "MYPRODUCT_V2.8"                     // User defined value which describes the originator of the event. e.g. PTVEMAPP_<system>_<version>, ptvemportal, jmeter_<testnumber> ...
}

Results

{
	"subscriptionID": "4565eb2a547f4f8c900ea64300814d52",
	"scemid": "X9X9X9X9X9",
	"responseStatus": {
		"errorCode": "SUCCESS",
		"message": "00000000000000000000000000000000"
	}
}

Notifications will be send to http://requestb.in/x9x9x9x9

Exceptions

validation / message	errorCode
Please provide a callback-URL	INVALID_NOTIFICATION_CONTENT
SCEM-ID should be a 10-digit, case-sensitive, alphanumeric identifier of an existing tour or stop.	SCEMID_INVALID

/subscription/ POST - (PUSH_MOBILE)

Notifications over PUSH_MOBILE subscription requires a OneSignal DeviceID. To occupy a DeviceID which is recognizable by D&A, OneSignal SDK should be used in your application and registered to it with following APP_ID: be00e13a-c405-4f93-81e2-6451e91b89f6 (note: subject to change).

{
	"subscription": {
	    "notificationType": "PUSH_MOBILE",      // type of notification channel, here PUSH_MOBILE
	    "topicType" : "TOUR_UPDATE",            // subscription topic: TOUR_UPDATE, ETA
	    "notificationDescription": {
	        "ident": "your_onesignal_identifier"// your device identifier acquired after registering to OneSignal
	    },
	    "scemid": "X9X9X9X9X9"                  // SCEM-ID of tour or stop you will receive notifications from
	},
	"source": "MYPRODUCT_V2.8"                  // User defined value which describes the originator of the event. e.g. PTVEMAPP_<system>_<version>, ptvemportal, jmeter_<testnumber> ...
}

Results

{
    "subscriptionID": "4565eb2a547f4f8c900ea64300814d52",
    "scemid": "X9X9X9X9X9",
    "responseStatus": {
        "errorCode": "SUCCESS",
        "message": "00000000000000000000000000000000"
    }
}

OneSignal SDK reference

Exceptions

validation / message	errorCode
Please provide a callback-URL	INVALID_NOTIFICATION_CONTENT
SCEM-ID should be a 10-digit, case-sensitive, alphanumeric identifier of an existing tour or stop.	SCEMID_INVALID

/subscription/batch/ POST - create multiple subscriptions at once

You can create multiple subscriptions to different SCEM-IDs at once https://driveandarrive-v1.cloud.ptvlogistics.com/em/subscription/batch?source=<myProduct_Vx.y> with only one HTTP-POST and the following data:

{
	"subscriptions": [
    {
		"notificationType": "CALLBACK_URL",                   // type of notification channel, here HTTP callback
		"notificationDescription": {                          // notification details
			"callBackURL": "http://requestb.in/x9x9x9x9", // URL of your server
			"ident": "your_identifier"                    // (optional) your personal identifier, e.g. system-XY - can be used for debugging purposes
		},
		"scemid": "X9X9X9X9X9"                                // SCEM-ID of tour or stop you will receive notifications from
	}, 
    {
		"notificationType": "PUSH_NON_MOBILE_SSE",            // type of notification channel, here SSE
		"notificationDescription": {
			"ident": "<identifier of SSE connection>"     // notificationHandler.GetNotificationHub(...).Ident in C#.net
		},
		"scemid": "X8X8X8X8X8"                                // SCEM-ID of tour or stop that should get notifications
	}
]
}

Results

{
	"subscriptionReferences": [{
		"subscriptionID": "4565eb2a547f4f8c900ea64300814d52",
		"scemid": "X9X9X9X9X9"
	}, {
		"subscriptionID": "1655eb2a547f4f8c900ea64300814d52",
		"scemid": "X8X8X8X8X8"
	}],
	"responseStatus": {
		"errorCode": "SUCCESS",
		"message": "00000000000000000000000000000000"
	}
}

Exceptions

validation / message	errorCode
For NotificationType URL_CALLBACK please provide a callback-URL, for PUSH_NON_MOBILE_SSE please provide an ident for the SSE connection.	INVALID_NOTIFICATION_CONTENT
SCEM-ID should be a 10-digit, case-sensitive, alphanumeric identifier of an existing tour or stop.	SCEMID_INVALID

/subscription/ DELETE - remove a subscription for a specified SCEM-ID by the assigned subscription ID

The method https://driveandarrive-v1.cloud.ptvlogistics.com/em/subscription?source=<myProduct_Vx.y>.

{
  "subscription":
   {
    "notificationType": "CALLBACK_URL",
    "topicType": "ETA",                              // (optional) ETA, TOUR_UPDATE
    "notificationDescription": {
        "callBackURL": "http://requestb.in/x9x9x9x9x9",
        "ident": "your_identifier"                   // optional
    },
    "subscriptionID":"4565eb2a547f4f8c900ea64300814d52",
    "scemid": "X9X9X9X9X9",
   }
}

Exceptions

validation / message	errorCode
SCEM-ID should be a 10-digit, case-sensitive, alphanumeric identifier of an existing tour or stop.	SCEMID_INVALID

/subscription/ GET - search subscriptions for a specified SCEM-ID by the assigned subscription ID(s) as comma separated list

To get a subscription to a specific SCEM-ID, e.g. X9X9X9X9X9 you have to call https://driveandarrive-v1.cloud.ptvlogistics.com/em/subscription/X9X9X9X9X9?source=<myProduct_Vx.y>%26subscriptionIDS=4565eb2a547f4f8c900ea64300814d52 and will get the following result, e.g. for a CALLBACK_URL:

{
  "subscriptions": [
   {
    "notificationType": "CALLBACK_URL",
    "topicType": "ETA",                              // (optional) ETA, TOUR_UPDATE
    "notificationDescription": {
        "callBackURL": "http://requestb.in/x9x9x9x9x9",
        "ident": "your_identifier"                   // optional
    },
    "subscriptionID":"4565eb2a547f4f8c900ea64300814d52",
    "scemid": "X9X9X9X9X9",
   }
  ],
  "responseStatus": 
  {
     "errorCode": "SUCCESS",
     "message": "000000000000"
  }
}

Exceptions

validation / message	errorCode
SCEM-ID should be a 10-digit, case-sensitive, alphanumeric identifier of an existing tour or stop.	SCEMID_INVALID